home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgramD2.iso / Database Designers / Rational Rose 2000 / Rational Setup.EXE / common / lib / Win32 / OLE.pm < prev    next >
Text File  |  1998-11-15  |  27KB  |  822 lines
  1. # The documentation is at the __END__
  2.  
  3. package Win32::OLE;
  4.  
  5. use strict;
  6. use vars qw($VERSION @ISA @EXPORT @EXPORT_OK @EXPORT_FAIL $AUTOLOAD
  7.         $CP $LCID $Warn $LastError);
  8.  
  9. $VERSION = '0.10';
  10.  
  11. use Carp;
  12. use Exporter;
  13. use DynaLoader;
  14. @ISA = qw(Exporter DynaLoader);
  15.  
  16. @EXPORT = qw();
  17. @EXPORT_OK = qw(CP_ACP CP_OEMCP in valof with OVERLOAD
  18.         DISPATCH_METHOD DISPATCH_PROPERTYGET
  19.         DISPATCH_PROPERTYPUT DISPATCH_PROPERTYPUTREF);
  20. @EXPORT_FAIL = qw(OVERLOAD);
  21.  
  22. sub export_fail {
  23.     shift;
  24.     if ($_[0] eq 'OVERLOAD') {
  25.     shift;
  26.     eval <<'OVERLOAD';
  27.         use overload '""'     => \&valof,
  28.                      '0+'     => \&valof,
  29.                      fallback => 1;
  30. OVERLOAD
  31.     }
  32.     return @_;
  33. }
  34.  
  35. bootstrap Win32::OLE;
  36.  
  37. $Warn = 1;
  38.  
  39. sub CP_ACP {0;}    # ANSI codepage
  40. sub CP_OEMCP {1;}  # OEM codepage
  41.  
  42. sub DISPATCH_METHOD          {1;}
  43. sub DISPATCH_PROPERTYGET     {2;}
  44. sub DISPATCH_PROPERTYPUT     {4;}
  45. sub DISPATCH_PROPERTYPUTREF  {8;}
  46.  
  47. sub COINIT_MULTITHREADED     {0;}  # Default
  48. sub COINIT_APARTMENTTHREADED {2;}  # Use single threaded apartment model
  49. sub COINIT_OLEINITIALIZE     {-1;} # Use OleInitialize instead of CoInitializeEx
  50.  
  51. # The following class methods are pure XS code. They will delegate
  52. # to Dispatch when called as object methods.
  53. #
  54. # - new(progid,destroy)
  55. # - GetActiveObject(progid)
  56. # - GetObject(pathname)
  57. # - QueryObjectType(object)
  58. #
  59. # - Initialize(coinit)
  60. # - Uninitialize()
  61. # - SpinMessageLoop()
  62. #
  63. # The following method is pure XS (and not available as OLE method)
  64. # - DESTROY()
  65. #
  66.  
  67.  
  68. # CreateObject is defined here only because it is documented in the
  69. # "Learning Perl on Win32 Systems" Gecko book. Please use Win32::OLE->new().
  70. sub CreateObject {
  71.     if (ref($_[0]) && UNIVERSAL::isa($_[0],'Win32::OLE')) {
  72.     $AUTOLOAD = 'CreateObject';
  73.     goto &AUTOLOAD;
  74.     }
  75.  
  76.     $_[1] = Win32::OLE->new($_[0]);
  77.     return defined $_[1];
  78. }
  79.  
  80. sub LastError {
  81.     unless (defined $_[0]) {
  82.     # Win32::OLE::LastError() will always return $Win32::OLE::LastError
  83.     return $LastError;
  84.     }
  85.  
  86.     if (ref($_[0]) && UNIVERSAL::isa($_[0],'Win32::OLE')) {
  87.     $AUTOLOAD = 'LastError';
  88.     goto &AUTOLOAD;
  89.     }
  90.  
  91.     no strict 'refs';
  92.     my $LastError = "$_[0]::LastError";
  93.     $$LastError = $_[1] if defined $_[1];
  94.     return $$LastError;
  95. }
  96.  
  97. sub Invoke {
  98.     my ($self, $method, @args) = @_;
  99.     my $retval;
  100.     $self->Dispatch($method, $retval, @args);
  101.     return $retval;
  102. }
  103.  
  104. sub SetProperty {
  105.     my ($self, $method, @args) = @_;
  106.     my $retval;
  107.     my $wFlags = DISPATCH_PROPERTYPUT;
  108.     if (@args) {
  109.     # If the value is an object then it must be set by reference!
  110.     my $value = $args[scalar(@args)-1];
  111.     if (UNIVERSAL::isa($value, 'Win32::OLE')) {
  112.         $wFlags = DISPATCH_PROPERTYPUTREF;
  113.     }
  114.     elsif (UNIVERSAL::isa($value,'Win32::OLE::Variant')) {
  115.         my $type = $value->Type;
  116.         # VT_DISPATCH and VT_UNKNOWN represent COM objects
  117.         $wFlags = DISPATCH_PROPERTYPUTREF if $type == 9 || $type == 13;
  118.     }
  119.     }
  120.     $self->Dispatch([$wFlags, $method], $retval, @args);
  121.     return $retval;
  122. }
  123.  
  124. sub AUTOLOAD {
  125.     my $self = shift;
  126.     my $retval;
  127.     $AUTOLOAD =~ s/.*:://o;
  128.     croak("Cannot autoload class method \"$AUTOLOAD\"") 
  129.       unless ref($self) && UNIVERSAL::isa($self, 'Win32::OLE');
  130.     my $success = $self->Dispatch($AUTOLOAD, $retval, @_);
  131.     unless (defined $success || ($^H & 0x200)) {
  132.     # Retry default method if C<no strict 'subs';>
  133.     $self->Dispatch(undef, $retval, $AUTOLOAD, @_);
  134.     }
  135.     return $retval;
  136. }
  137.  
  138. sub in {
  139.     my @res;
  140.     while (@_) {
  141.     my $this = shift;
  142.     if (UNIVERSAL::isa($this, 'Win32::OLE')) {
  143.         require Win32::OLE::Enum;
  144.         push @res, Win32::OLE::Enum->All($this);
  145.     }
  146.     elsif (ref($this) eq 'ARRAY') {
  147.         push @res, @$this;
  148.     }
  149.     else {
  150.         push @res, $this;
  151.     }
  152.     }
  153.     return @res;
  154. }
  155.  
  156. sub valof {
  157.     my $arg = shift;
  158.     if (UNIVERSAL::isa($arg, 'Win32::OLE')) {
  159.     require Win32::OLE::Variant;
  160.     my ($class) = overload::StrVal($arg) =~ /^([^=]+)=/;
  161.     no strict 'refs';
  162.     local $Win32::OLE::Variant::CP = ${$class."::CP"};
  163.     local $Win32::OLE::Variant::LCID = ${$class."::LCID"};
  164.     use strict 'refs';
  165.     # VT_EMPTY variant for return code
  166.     my $variant = Win32::OLE::Variant->new(0,0);
  167.     $arg->Dispatch(undef, $variant);
  168.     return $variant->Value;
  169.     }
  170.     $arg = $arg->Value if UNIVERSAL::can($arg, 'Value');
  171.     return $arg;
  172. }
  173.  
  174. sub with {
  175.     my $object = shift;
  176.     while (@_) {
  177.     my $property = shift;
  178.     $object->{$property} = shift;
  179.     }
  180. }
  181.  
  182. ########################################################################
  183.  
  184. package Win32::OLE::Tie;
  185.  
  186. # Only retry default method under C<no strict 'subs';>
  187.  
  188. sub FETCH {
  189.     my ($self,$key) = @_;
  190.     $self->Fetch($key, !($^H & 0x200));
  191. }
  192.  
  193. sub STORE {
  194.     my ($self,$key,$value) = @_;
  195.     $self->Store($key, $value, !($^H & 0x200));
  196. }
  197.  
  198. 1;
  199.  
  200. ########################################################################
  201.  
  202. __END__
  203.  
  204. =head1 NAME
  205.  
  206. Win32::OLE - OLE Automation extensions
  207.  
  208. =head1 SYNOPSIS
  209.  
  210.     $ex = Win32::OLE->new('Excel.Application') or die "oops\n";
  211.     $ex->Amethod("arg")->Bmethod->{'Property'} = "foo";
  212.     $ex->Cmethod(undef,undef,$Arg3);
  213.     $ex->Dmethod($RequiredArg1, {NamedArg1 => $Value1, NamedArg2 => $Value2});
  214.  
  215.     $wd = Win32::OLE->GetObject("D:\\Data\\Message.doc");
  216.     $xl = Win32::OLE->GetActiveObject("Excel.Application");
  217.  
  218. =head1 DESCRIPTION
  219.  
  220. This module provides an interface to OLE Automation from Perl.
  221. OLE Automation brings VisualBasic like scripting capabilities and
  222. offers powerful extensibility and the ability to control many Win32
  223. applications from Perl scripts.
  224.  
  225. The Win32::OLE module uses the IDispatch interface exclusively. It is
  226. not possible to access a custom OLE interface. OLE events and OCX's are
  227. currently not supported.
  228.  
  229. =head2 Methods
  230.  
  231. =over 8
  232.  
  233. =item Win32::OLE->new(PROGID [, DESTRUCTOR])
  234.  
  235. OLE Automation objects are created using the new() method, the second
  236. argument to which must be the OLE program id or class id of the
  237. application to create.  Return value is undef if the attempt to create
  238. an OLE connection failed for some reason. The optional third argument
  239. specifies a DESTROY-like method. This can be either a CODE reference
  240. or a string containing an OLE method name. It can be used to cleanly
  241. terminate OLE objects in case the Perl program dies in the middle of
  242. OLE activity.
  243.  
  244. The object returned by the new() method can be used to invoke
  245. methods or retrieve properties in the same fashion as described
  246. in the documentation for the particular OLE class (eg. Microsoft
  247. Excel documentation describes the object hierarchy along with the
  248. properties and methods exposed for OLE access).
  249.  
  250. Optional parameters on method calls can be omitted by using C<undef>
  251. as a placeholder. A better way is to use named arguments, as the
  252. order of optional parameters may change in later versions of the OLE
  253. server application. Named parameters can be specified in a reference
  254. to a hash as the last parameter to a method call.
  255.  
  256. Properties can be retrieved or set using hash syntax, while methods
  257. can be invoked with the usual perl method call syntax. The C<keys>
  258. and C<each> functions can be used to enumerate an object's properties.
  259. Beware that a property is not always writable or even readable (sometimes
  260. raising exceptions when read while being undefined).
  261.  
  262. If a method or property returns an embedded OLE object, method
  263. and property access can be chained as shown in the examples below.
  264.  
  265. =item Win32::OLE->GetActiveObject(CLASS)
  266.  
  267. The GetActiveObject class method returns an OLE reference to a
  268. running instance of the specified OLE automation server. It returns
  269. C<undef> if the server is not currently active. It will croak if
  270. the class is not even registered.
  271.  
  272. =item Win32::OLE->GetObject(MONIKER)
  273.  
  274. The GetObject class method returns an OLE reference to the specified
  275. object. The object is specified by a pathname optionally followed by
  276. additional item subcomponent separated by exclamation marks '!'.
  277.  
  278. =item Win32::OLE->Initialize(COINIT)
  279.  
  280. The C<Initialize> class method can be used to specify an alternative
  281. apartment model for the Perl thread. It must be called before the
  282. first object is created. Valid values for COINIT are:
  283.  
  284.   Win32::OLE::COINIT_APARTMENTTHREADED - single threaded
  285.   Win32::OLE::COINIT_MULTITHREADED     - the default
  286.   Win32::OLE::COINIT_OLEINITIALIZE     - single threaded, additional OLE stuff
  287.  
  288. COINIT_OLEINITIALIZE is sometimes needed when an OLE object uses
  289. additional OLE compound document technologies not available from the
  290. normal COM subsystem (for example MAPI.Session seems to require it).
  291. Both COINIT_OLEINITIALIZE and COINIT_APARTMENTTHREADED create a hidden
  292. top level window and a message queue for the Perl process. This may
  293. create problems with other application, because Perl normally doesn't
  294. process its message queue. This means programs using synchronous
  295. communication between applications (such as DDE initiation), may hang
  296. until Perl makes another OLE method call/property access or terminates.
  297. This applies to InstallShield setups and many things started to shell
  298. associations. Please try to utilize the C<Win32::OLE-E<gt>SpinMessageLoop>
  299. and C<Win32::OLE-E<gt>Uninitialize> methods if you can not use the default
  300. COINIT_MULTITHREADED model.
  301.  
  302. =item OBJECT->Invoke(METHOD,ARGS)
  303.  
  304. The C<Invoke> object method is an alternate way to invoke OLE
  305. methods. It is normally equivalent to C<$OBJECT->METHOD(@ARGS)>. This
  306. function must be used if the METHOD name contains characters not valid
  307. in a Perl variable name (like foreign language characters). It can
  308. also be used to invoke the default method of an object even if the
  309. default method has not been given a name in the type library. In this
  310. case use <undef> or C<''> as the method name. To invoke an OLE objects
  311. native C<Invoke> method (if such a thing exists), please use:
  312.  
  313.     $Object->Invoke('Invoke', @Args);
  314.  
  315. =item Win32::OLE->LastError()
  316.  
  317. The C<LastError> class method returns the last recorded OLE
  318. error. This is a dual value like the C<$!> variable: in a numeric
  319. context it returns the error number and in a string context it returns
  320. the error message.
  321.  
  322. The last OLE error is automatically reset by a successful OLE
  323. call. The numeric value can also explicitly be set by a call (which will
  324. discard the string value):
  325.  
  326.     Win32::OLE->LastError(0);
  327.  
  328. =item Win32::OLE->QueryObjectType(OBJECT)
  329.  
  330. The C<QueryObjectType> class method returns a list of the type library
  331. name and the objects class name. In a scalar context it returns the
  332. class name only. It returns C<undef> when the type information is not
  333. available.
  334.  
  335. =item OBJECT->SetProperty(NAME,ARGS,VALUE)
  336.  
  337. The C<SetProperty> method allows to modify properties with arguments,
  338. which is not supported by the hash syntax. The hash form
  339.  
  340.     $Object->{Property} = $Value;
  341.  
  342. is equivalent to
  343.  
  344.     $Object->SetProperty('Property', $Value);
  345.  
  346. Arguments must be specified between the property name and the new value.
  347. It is not possible to use "named argument" syntax with this function
  348. because the new value must be the last argument to C<SetProperty>.
  349.  
  350. This method hides any native OLE object method called C<SetProperty>.
  351. The native method will still be available through the C<Invoke> method:
  352.  
  353.     $Object->Invoke('SetProperty', @Args);
  354.  
  355. =item Win32::OLE->SpinMessageLoop
  356.  
  357. This class method retrieves all pending messages from the message queue
  358. and dispatches them to their respective window procedures. Calling this
  359. method is only necessary when not using the COINIT_MULTITHREADED model.
  360. All OLE method calls and property accesses automatically process the
  361. message queue.
  362.  
  363. =item Win32::OLE->Uninitialize
  364.  
  365. The C<Uninitialize> class method uninitializes the OLE subsystem. It
  366. also destroys the hidden top level window created by OLE for single
  367. threaded apartments. All OLE objects will become invalid after this call!
  368. It is possible to call the C<Initialize> class method again with a different
  369. apartment model after shutting down OLE with C<Uninitialize>.
  370.  
  371. =back
  372.  
  373. Whenever Perl does not find a method name in the Win32::OLE package it
  374. is automatically used as the name of an OLE method and this method call
  375. is dispatched to the OLE server.
  376.  
  377. There is one special hack built into the module: If a method or property 
  378. name could not be resolved with the OLE object, then the default method
  379. of the object is called with the method name as its first parameter. So
  380.  
  381.     my $Sheet = $Worksheets->Table1;
  382. or
  383.     my $Sheet = $Worksheets->{Table1};
  384.  
  385. is resolved as
  386.  
  387.     my $Sheet = $Worksheet->Item('Table1');
  388.  
  389. provided that the C<$Worksheets> object doesnot have a C<Table1> method
  390. or property. This hack has been introduced to call the default method
  391. of collections which did not name the method in their type library. The
  392. recommended way to call the "unnamed" default method is:
  393.  
  394.     my $Sheet = $Worksheets->Invoke('', 'Table1');
  395.  
  396. This special hack is disabled under C<use strict 'subs';>.
  397.  
  398. =head2 Functions
  399.  
  400. The following functions are not exported by default.
  401.  
  402. =over 8
  403.  
  404. =item in(COLLECTION)
  405.  
  406. If COLLECTION is an OLE collection object then C<in $COLLECTION>
  407. returns a list of all members of the collection. This is a shortcut
  408. for C<Win32::OLE::Enum->All($COLLECTION)>. It is most commonly used in
  409. a C<foreach> loop:
  410.  
  411.     foreach my $value (in $collection) {
  412.         # do something with $value here
  413.     }
  414.  
  415. =item valof(OBJECT)
  416.  
  417. Normal assignment of Perl OLE objects creates just another reference
  418. to the OLE object. The C<valof> function explictly dereferences the
  419. object (through the default method) and returns the value of the object.
  420.  
  421.     my $RefOf = $Object;
  422.     my $ValOf = valof $Object;
  423.         $Object->{Value} = $NewValue;
  424.  
  425. Now C<$ValOf> still contains the old value wheras C<$RefOf> would
  426. resolve to the C<$NewValue> because it is still a reference to
  427. C<$Object>.
  428.  
  429. The C<valof> function can also be used to convert Win32::OLE::Variant
  430. objects to Perl values.
  431.  
  432. =item with(OBJECT, PROPERTYNAME => VALUE, ...)
  433.  
  434. This function provides a concise way to set the values of multiple
  435. properties of an object.  It iterates over its arguments doing
  436. C<$OBJECT->{PROPERTYNAME} = $VALUE> on each trailing pair.
  437.  
  438. =back
  439.  
  440. =head2 Overloading
  441.  
  442. The Win32::OLE objects can be overloaded to automatically convert to
  443. their values whenever they are used in a bool, numeric or string
  444. context. This is not enabled by default. You have to request it
  445. through the C<OVERLOAD> pseudoexport:
  446.  
  447.     use Win32::OLE qw(in valof with OVERLOAD);
  448.  
  449. You can still get the original string representation of an object
  450. (C<Win32::OLE=0xDEADBEEF>), e.g. for debugging, by using the 
  451. C<overload::StrVal> method:
  452.  
  453.     print overload::StrVal($object), "\n";
  454.  
  455. Please note that C<OVERLOAD> is a global setting. If any module enables
  456. Win32::OLE overloading then it's active everywhere.
  457.  
  458. =head2 Class Variables
  459.  
  460. =over 8
  461.  
  462. =item $Win32::OLE::CP
  463.  
  464. This variable is used to determine the codepage used by all
  465. translations between Perl strings and Unicode strings used by the OLE
  466. interface. The default value is CP_ACP, which is the default ANSI
  467. codepage. It can also be set to CP_OEMCP which is the default OEM
  468. codepage. Both constants are not exported by default.
  469.  
  470. =item $Win32::OLE::LCID
  471.  
  472. This variable controls the locale idnetifier used for all OLE calls.
  473. It is set to LOCALE_NEUTRAL by default. Please check the
  474. L<Win32::OLE::NLS> module for other locale related information.
  475.  
  476. =item $Win32::OLE::Warn
  477.  
  478. This variable determines the behavior of the Win32::OLE module when
  479. an error happens. Valid values are:
  480.  
  481.     0    Ignore error, return undef
  482.     1    Carp::carp if $^W is set (-w option)
  483.     2    always Carp::carp
  484.     3    Carp::croak
  485.  
  486. The error number and message (without Carp line/module info) are
  487. available through the C<Win32::OLE->LastError> class method.
  488.  
  489. =back
  490.  
  491. =head1 EXAMPLES
  492.  
  493. Here is a simple Microsoft Excel application.
  494.  
  495.     use Win32::OLE;
  496.  
  497.     # use existing instance if Excel is already running
  498.     eval {$ex = Win32::OLE->GetActiveObject('Excel.Application')};
  499.     die "Excel not installed" if $@;
  500.     unless (defined $ex) {
  501.         $ex = Win32::OLE->new('Excel.Application', sub {$_[0]->Quit;})
  502.             or die "Oops, cannot start Excel";
  503.     }
  504.     
  505.     # open an existing workbook
  506.     $book = $ex->Workbooks->Open( 'test.xls' );
  507.     
  508.     # write to a particular cell
  509.     $sheet = $book->Worksheets(1);
  510.     $sheet->Cells(1,1)->{Value} = "foo";
  511.  
  512.         # write a 2 rows by 3 columns range
  513.         $sheet->Range("A8:C9")->{Value} = [[ undef, 'Xyzzy', 'Plugh' ],
  514.                                            [ 42,    'Perl',  3.1415  ]];
  515.  
  516.         # print "XyzzyPerl"
  517.         $array = $sheet->Range("A8:B9")->{Value};
  518.         print $array[0][1] . $array[1][1];
  519.  
  520.     # save and exit
  521.     $book->Save;
  522.     undef $book;
  523.     undef $ex;
  524.  
  525. Please note the destructor specified on the Win32::OLE->new method. It ensures
  526. that Excel will shutdown properly even if the Perl program dies. Otherwise
  527. there could be a process leak if your application dies after having opened
  528. an OLE instance of Excel. It is the responsibility of the module user to
  529. make sure that all OLE objects are cleaned up properly!
  530.  
  531. Here is an example of using Variant data types.
  532.  
  533.     use Win32::OLE;
  534.     $ex = Win32::OLE->new('Excel.Application', \&OleQuit) or die "oops\n";
  535.     $ex->{Visible} = 1;
  536.     $ex->Workbooks->Add;
  537.     $ovR8 = Variant(VT_R8, "3 is a good number");
  538.     $ex->Range("A1")->{Value} = $ovR8;
  539.     $ex->Range("A2")->{Value} = Variant(VT_DATE, 'Jan 1,1970');
  540.  
  541.     sub OleQuit { 
  542.         my $self = shift; 
  543.         $self->Quit; 
  544.     }
  545.  
  546. The above will put value "3" in cell A1 rather than the string
  547. "3 is a good number".  Cell A2 will contain the date.
  548.  
  549. Similarly, to invoke a method with some binary data, you can
  550. do the following:
  551.  
  552.     $obj->Method( Variant(VT_UI1, "foo\000b\001a\002r") );
  553.  
  554. Here is a wrapper class that basically delegates everything but
  555. new() and DESTROY().  The wrapper class shown here is another way to
  556. properly shut down connections if your application is liable to die
  557. without proper cleanup.  Your own wrappers will probably do something
  558. more specific to the particular OLE object you may be dealing with,
  559. like overriding the methods that you may wish to enhance with your
  560. own.
  561.  
  562.     package Excel;
  563.     use Win32::OLE;
  564.     
  565.     sub new {
  566.         my $s = {};
  567.         if ($s->{Ex} = Win32::OLE->new('Excel.Application')) {
  568.         return bless $s, shift;
  569.         }
  570.         return undef;
  571.     }
  572.     
  573.     sub DESTROY {
  574.         my $s = shift;
  575.         if (exists $s->{Ex}) {
  576.         print "# closing connection\n";
  577.         $s->{Ex}->Quit;
  578.         return undef;
  579.         }
  580.     }
  581.     
  582.     sub AUTOLOAD {
  583.         my $s = shift;
  584.         $AUTOLOAD =~ s/^.*:://;
  585.         $s->{Ex}->$AUTOLOAD(@_);
  586.     }
  587.     
  588.     1;
  589.  
  590. The above module can be used just like Win32::OLE, except that
  591. it takes care of closing connections in case of abnormal exits.
  592. Note that the effect of this specific example can be easier accomplished
  593. using the optional destructor argument of Win32::OLE::new:
  594.  
  595.     my $Excel = Win32::OLE->new('Excel.Application', sub {$_[0]->Quit;});
  596.  
  597. Note that the delegation shown in the earlier example is not the same as
  598. true subclassing with respect to further inheritance of method calls in your
  599. specialized object.  See L<perlobj>, L<perltoot> and L<perlbot> for details.
  600. True subclassing (available by setting C<@ISA>) is also feasible,
  601. as the following example demonstrates:
  602.  
  603.     #
  604.     # Add error reporting to Win32::OLE
  605.     #
  606.     
  607.     package Win32::OLE::Strict;
  608.     use Carp;
  609.     use Win32::OLE;
  610.     
  611.     use strict qw(vars);
  612.     use vars qw($AUTOLOAD @ISA);
  613.     @ISA = qw(Win32::OLE);
  614.     
  615.     sub AUTOLOAD {
  616.         my $obj = shift;
  617.         $AUTOLOAD =~ s/^.*:://;
  618.         my $meth = $AUTOLOAD;
  619.         $AUTOLOAD = "SUPER::" . $AUTOLOAD;
  620.         my $retval = $obj->$AUTOLOAD(@_);
  621.         unless (defined($retval) || $AUTOLOAD eq 'DESTROY') {
  622.         my $err = Win32::OLE::LastError();
  623.         croak(sprintf("$meth returned OLE error 0x%08x",$err))
  624.           if $err;
  625.         }
  626.         return $retval;
  627.     }
  628.     
  629.     1;
  630.  
  631. This package inherits the constructor C<new()> from the Win32::OLE
  632. package. It is important to note that you cannot later rebless a
  633. Win32::OLE object as some information about the package is cached by
  634. the object. Always invoke the C<new()> constructor through the right
  635. package!
  636.  
  637. Here's how the above class will be used:
  638.  
  639.     use Win32::OLE::Strict;
  640.     my $Excel = Win32::OLE::Strict->new('Excel.Application', 'Quit');
  641.     my $Books = $Excel->Workbooks;
  642.     $Books->UnknownMethod(42);
  643.  
  644. In the sample above the call to C<UnknownMethod> will be caught with
  645.  
  646.     UnknownMethod returned OLE error 0x80020009 at test.pl line 5
  647.  
  648. because the Workbooks object inherits the class C<Win32::OLE::Strict> from the
  649. C<$Excel> object.
  650.  
  651. =head1 NOTES
  652.  
  653. =head2 Hints for Microsoft Office automation
  654.  
  655. =over 8
  656.  
  657. =item Documentation
  658.  
  659. The object model for the Office applications is defined in the Visual Basic
  660. reference guides for the various applications. These are typically not
  661. installed by default during the standard installation. They can be added
  662. later by rerunning the setup program with the custom install option.
  663.  
  664. =item Class, Method and Property names
  665.  
  666. The names have been changed between different versions of Office. For
  667. example C<Application> was a method in Office 95 and is a property in
  668. Office97. Therefore it will not show up in the list of property names
  669. C<keys %$object> when querying an Office 95 object.
  670.  
  671. The class names are not always identical to the method/property names
  672. producing the object. E.g. the C<Workbook> method returns an object of
  673. type C<Workbook> in Office 95 and C<_Workbook> in Office 97.
  674.  
  675. =item Moniker (GetObject support)
  676.  
  677. Office applications seem to implement file monikers only. For example
  678. it seems to be impossible to retrieve a specific worksheet object through
  679. C<GetObject("File.XLS!Sheet")>. Furthermore, in Excel 95 the moniker starts
  680. a Worksheet object and in Excel 97 it returns a Workbook object. You can use
  681. either the Win32::OLE::QueryObjectType class method or the $object->{Version}
  682. property to write portable code.
  683.  
  684. =item Enumeration of collection objects
  685.  
  686. Enumerations seem to be incompletely implemented. Office 95 application don't
  687. seem to support neither the Reset() nor the Clone() methods. The Clone()
  688. method is still unimplemented in Office 97. A single walk through the
  689. collection similar to Visual Basics C<for each> construct does work however.
  690.  
  691. =item Localization
  692.  
  693. Starting with Office 97 Microsoft has changed the localized class, method and
  694. property names back into English. Note that string, date and currency
  695. arguments are still subject to locale specific interpretation. Perl uses the
  696. system default locale for all OLE transaction whereas Visual Basic uses a 
  697. type library specific locale. A Visual Basic script would use "R1C1" in string
  698. arguments to specify relative references. A Perl script running on a German
  699. language Windows would have to use "Z1S1". Set the C<$Win32::OLE::LCID> class
  700. variable to an English locale to write portable scripts. This variable should
  701. not be changed after creating the OLE objects; some methods seem to randomly
  702. fail if the locale is changed on the fly.
  703.  
  704. =item SaveAs method in Word 97 doesn't work
  705.  
  706. This is an known bug in Word 97. Search the MS knowledge base for Word /
  707. Foxpro incompatibility. That problem applies to the Perl OLE interface as
  708. well. A workaround is to use the WordBasic compatibility object. It doesn't
  709. support all the options of the native method though.
  710.  
  711.     $Word->WordBasic->FileSaveAs($file);
  712.  
  713. The problem seems to be fixed by applying the Office 97 Service Release 1.
  714.  
  715. =item Randomly failing method calls
  716.  
  717. It seems like modifying objects that are not selected/activated is sometimes
  718. fragile. Most of these problems go away if the chart/sheet/document is
  719. selected or activated before being manipulated (just like an interactive
  720. user would automatically do it).
  721.  
  722. =back
  723.  
  724. =head2 Incompatibilities
  725.  
  726. There are some incompatibilities with the version distributed by Activeware
  727. (as of build 306).
  728.  
  729. =over 8
  730.  
  731. =item 1
  732.  
  733. The package name has changed from "OLE" to "Win32::OLE".
  734.  
  735. =item 2
  736.  
  737. All functions of the form "Win32::OLEFoo" are now "Win32::OLE::Foo",
  738. though the old names are temporarily accomodated.  Win32::OLECreateObject()
  739. was changed to Win32::OLE::CreateObject(), and is now called
  740. Win32::OLE::new() bowing to established convention for naming constructors.
  741. The old names should be considered deprecated, and will be removed in the
  742. next version.
  743.  
  744. =item 3
  745.  
  746. Package "OLE::Variant" is now "Win32::OLE::Variant".
  747.  
  748. =item 4
  749.  
  750. The Variant function is new, and is exported by default.  So are
  751. all the VT_XXX type constants.
  752.  
  753. =item 5
  754.  
  755. The support for collection objects has been moved into the package
  756. Win32::OLE::Enum. The C<keys %$object> method is now used to enumerate
  757. the properties of the object.
  758.  
  759. =back
  760.  
  761. =head2 Bugs and Limitations
  762.  
  763. =over 8
  764.  
  765. =item 1
  766.  
  767. To invoke a native OLE method with the same name as one of the
  768. Win32::OLE methods (C<Dispatch>, C<Invoke>, C<SetProperty>, C<DESTROY>,
  769. etc.), you have to use the C<Invoke> method:
  770.  
  771.     $Object->Invoke('Dispatch', @AdditionalArgs);
  772.  
  773. The same is true for names exported by the Exporter or the Dynaloader
  774. modules, e.g.: C<export>, C<export_to_level>, C<import>,
  775. C<_push_tags>, C<export_tags>, C<export_ok_tags>, C<export_fail>,
  776. C<require_version>, C<dl_load_flags>,
  777. C<croak>, C<bootstrap>, C<dl_findfile>, C<dl_expandspec>, 
  778. C<dl_find_symbol_anywhere>, C<dl_load_file>, C<dl_find_symbol>,
  779. C<dl_undef_symbols>, C<dl_install_xsub> and C<dl_error>.
  780.  
  781. =item 2
  782.  
  783. The class global variables C<$Win32::OLE::WARN> and C<$Win32::OLE::LCID>
  784. must currently be accessed directly. An API to manipulate these settings
  785. will be made available in the future.
  786.  
  787. =back
  788.  
  789. =head1 SEE ALSO
  790.  
  791. The documentation for L<Win32::OLE::Const>, L<Win32::OLE::Enum>,
  792. L<Win32::OLE::NLS> and L<Win32::OLE::Variant> contains additional
  793. information about OLE support for Perl on Win32.
  794.  
  795. =head1 AUTHORS
  796.  
  797. Originally put together by the kind people at Hip and Activeware.
  798.  
  799. Gurusamy Sarathy <gsar@umich.edu> subsequently fixed several major
  800. bugs, memory leaks, and reliability problems, along with some
  801. redesign of the code.
  802.  
  803. Jan Dubois <jan.dubois@ibm.net> pitched in with yet more massive redesign,
  804. added support for named parameters, and other significant enhancements.
  805.  
  806. =head1 COPYRIGHT
  807.  
  808.     (c) 1995 Microsoft Corporation. All rights reserved. 
  809.     Developed by ActiveWare Internet Corp., http://www.ActiveWare.com
  810.  
  811.     Other modifications Copyright (c) 1997, 1998 by Gurusamy Sarathy
  812.     <gsar@umich.edu> and Jan Dubois <jan.dubois@ibm.net>
  813.  
  814.     You may distribute under the terms of either the GNU General Public
  815.     License or the Artistic License, as specified in the README file.
  816.  
  817. =head1 VERSION
  818.  
  819. Version 0.10    9 September 1998
  820.  
  821. =cut
  822.